Skip to content

feat(kwin):python绑定#1375

Merged
MistEO merged 4 commits into
MaaXYZ:mainfrom
lava114514:feat/kwin-wayland
Jun 20, 2026
Merged

feat(kwin):python绑定#1375
MistEO merged 4 commits into
MaaXYZ:mainfrom
lava114514:feat/kwin-wayland

Conversation

@lava114514

@lava114514 lava114514 commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

为KWinController添加python绑定

Summary by Sourcery

为 Linux 上的 KWin Wayland 控制器添加一个 Python 绑定以及基础测试覆盖。

新功能:

  • 在 Python 绑定中暴露一个 KWinController 类,通过 PipeWire/xdg-desktop-portal 和 /dev/uinput 控制 KWin。

测试:

  • 添加一个 Python 绑定测试,用于创建 KWinController、验证其基础属性,并在控制器不可用时优雅地跳过测试。
Original summary in English

Summary by Sourcery

Add a Python binding and basic test coverage for the KWin Wayland controller on Linux.

New Features:

  • Expose a KWinController class in the Python bindings to control KWin via PipeWire/xdg-desktop-portal and /dev/uinput.

Tests:

  • Add a Python binding test that creates a KWinController, validates its basic properties, and skips gracefully when the controller is unavailable.

新特性:

  • 在 Python 绑定中暴露 KWinController 类,通过 PipeWire/xdg-desktop-portal 和 /dev/uinput 驱动 KWin。

测试:

  • 添加一个 Python 绑定测试,用于创建 KWinController 并验证其基本属性和空操作行为;在不可用时能优雅地跳过。
Original summary in English

Summary by Sourcery

为 Linux 上的 KWin Wayland 控制器添加一个 Python 绑定以及基础测试覆盖。

新功能:

  • 在 Python 绑定中暴露一个 KWinController 类,通过 PipeWire/xdg-desktop-portal 和 /dev/uinput 控制 KWin。

测试:

  • 添加一个 Python 绑定测试,用于创建 KWinController、验证其基础属性,并在控制器不可用时优雅地跳过测试。
Original summary in English

Summary by Sourcery

Add a Python binding and basic test coverage for the KWin Wayland controller on Linux.

New Features:

  • Expose a KWinController class in the Python bindings to control KWin via PipeWire/xdg-desktop-portal and /dev/uinput.

Tests:

  • Add a Python binding test that creates a KWinController, validates its basic properties, and skips gracefully when the controller is unavailable.

@lava114514 lava114514 marked this pull request as ready for review June 20, 2026 08:13

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - 我发现了 1 个问题,并留下了一些整体层面的反馈:

  • binding_test.py__main__ 代码块中,你注释掉了所有现有的测试调用,只运行 test_kwin_controller_create;这实际上在直接运行该文件时禁用了其余的绑定测试,因此要么恢复这些调用,要么把 KWin 相关的测试移动到现有的测试序列中。
  • KWinController.__init__ 中,在不检查符号是否存在的情况下直接调用 Library.framework().MaaKWinControllerCreate,会在符号缺失的环境中于导入时抛出 AttributeError;建议使用 hasattr 或 try/except 做保护,并改为抛出一个更清晰、可控的 RuntimeError,而不是依赖测试去处理这个 AttributeError
给 AI 代理的提示
Please address the comments from this code review:

## Overall Comments
- In `binding_test.py`'s `__main__` block you've commented out all existing test calls and only run `test_kwin_controller_create`; this effectively disables the rest of the binding tests when the file is run directly, so either restore those calls or move the KWin-specific test into the existing sequence.
- In `KWinController.__init__`, calling `Library.framework().MaaKWinControllerCreate` without checking for its presence will raise an `AttributeError` at import time in environments where the symbol is missing; consider guarding this with `hasattr` or a try/except and raising a clearer, controlled `RuntimeError` instead of relying on tests to handle the `AttributeError`.

## Individual Comments

### Comment 1
<location path="source/binding/Python/maa/controller.py" line_range="1095" />
<code_context>
+        self._set_kwin_api_properties()
+
+        self._handle = Library.framework().MaaKWinControllerCreate(
+            device_node.encode(),
+            screen_width,
+            screen_height,
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Consider normalizing `device_node` more defensively before encoding.

This assumes `device_node` is a `str` and uses the default encoding. If a `pathlib.Path` or `bytes` is passed, this can fail or double-encode. Using `os.fspath(device_node)` with `os.fsencode(...)`, or at least validating the type, would make this safer for typical path-like inputs and non-ASCII paths.

Suggested implementation:

```python
        super().__init__()
        self._set_kwin_api_properties()

        normalized_device_node = os.fsencode(os.fspath(device_node))

        self._handle = Library.framework().MaaKWinControllerCreate(
            normalized_device_node,
            screen_width,
            screen_height,
            MaaBool(use_win32_vk_code),
        )

```

1. Ensure `os` is imported at the top of `source/binding/Python/maa/controller.py`, e.g. `import os`.
2. If this module already defines a helper for path normalization/encoding, prefer using that helper instead of introducing the `normalized_device_node` variable directly, to stay consistent with the rest of the codebase.
</issue_to_address>

Sourcery 对开源项目免费——如果你喜欢我们的评审,请考虑分享 ✨
请帮我变得更有用!请在每条评论上点击 👍 或 👎,我会根据这些反馈改进对你的评审。
Original comment in English

Hey - I've found 1 issue, and left some high level feedback:

  • In binding_test.py's __main__ block you've commented out all existing test calls and only run test_kwin_controller_create; this effectively disables the rest of the binding tests when the file is run directly, so either restore those calls or move the KWin-specific test into the existing sequence.
  • In KWinController.__init__, calling Library.framework().MaaKWinControllerCreate without checking for its presence will raise an AttributeError at import time in environments where the symbol is missing; consider guarding this with hasattr or a try/except and raising a clearer, controlled RuntimeError instead of relying on tests to handle the AttributeError.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- In `binding_test.py`'s `__main__` block you've commented out all existing test calls and only run `test_kwin_controller_create`; this effectively disables the rest of the binding tests when the file is run directly, so either restore those calls or move the KWin-specific test into the existing sequence.
- In `KWinController.__init__`, calling `Library.framework().MaaKWinControllerCreate` without checking for its presence will raise an `AttributeError` at import time in environments where the symbol is missing; consider guarding this with `hasattr` or a try/except and raising a clearer, controlled `RuntimeError` instead of relying on tests to handle the `AttributeError`.

## Individual Comments

### Comment 1
<location path="source/binding/Python/maa/controller.py" line_range="1095" />
<code_context>
+        self._set_kwin_api_properties()
+
+        self._handle = Library.framework().MaaKWinControllerCreate(
+            device_node.encode(),
+            screen_width,
+            screen_height,
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Consider normalizing `device_node` more defensively before encoding.

This assumes `device_node` is a `str` and uses the default encoding. If a `pathlib.Path` or `bytes` is passed, this can fail or double-encode. Using `os.fspath(device_node)` with `os.fsencode(...)`, or at least validating the type, would make this safer for typical path-like inputs and non-ASCII paths.

Suggested implementation:

```python
        super().__init__()
        self._set_kwin_api_properties()

        normalized_device_node = os.fsencode(os.fspath(device_node))

        self._handle = Library.framework().MaaKWinControllerCreate(
            normalized_device_node,
            screen_width,
            screen_height,
            MaaBool(use_win32_vk_code),
        )

```

1. Ensure `os` is imported at the top of `source/binding/Python/maa/controller.py`, e.g. `import os`.
2. If this module already defines a helper for path normalization/encoding, prefer using that helper instead of introducing the `normalized_device_node` variable directly, to stay consistent with the rest of the codebase.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

Comment thread source/binding/Python/maa/controller.py Outdated
@MistEO MistEO merged commit ec397ca into MaaXYZ:main Jun 20, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants